Automation

BindAI Automation provides the foundation for building event-driven applications and workflows. Automation allows an application to react when something happens, such as an agent event, tool execution, workflow event, or another event published through BindAI’s event system. The current automation package provides primitives for:

Automation definitions
Automation execution state
Automation run history
Event triggers
Trigger management
Background automation workers

The architecture is intentionally small so that additional automation capabilities can be added incrementally.

Automation Architecture

The current architecture separates automation definitions, execution state, historical records, and event triggers:

AutomationDefinition
        |
        v
  AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore    AutomationRunHistory
        |                      |
        v                      v
Current Run State       Historical Runs

Event-driven automation is provided separately:

Event Source
     |
     v
  EventBus
     |
     v
EventTrigger
     |
     v
  Target

Triggers provide the boundary between an event source and an automation action. For example:

Agent
  |
  v
EventBus
  |
  v
EventTrigger
  |
  v
Workflow / Function / Application Logic

This allows automation behavior to remain separate from the components that produce events.

Automation Package

The automation package is provided by:

import bindai_automation

The public API currently includes:

from bindai_automation import (
    AutomationDefinition,
    AutomationRun,
    AutomationRunHistory,
    AutomationStateStore,
    AutomationWorker,
    MemoryAutomationRunHistory,
    MemoryAutomationStateStore,
    Trigger,
    EventTrigger,
    TriggerRegistry,
)

Automation Definitions

AutomationDefinition describes an automation and the executable target it invokes.

from bindai_automation import AutomationDefinition

automation = AutomationDefinition(
    name="my-automation",
    target=my_executable,
)

A definition provides:

id — unique automation definition identifier
name — human-readable automation name
version — definition version, starting at 1
target — the bindai-core executable invoked by the automation
metadata — optional application-defined metadata

Definitions can be cloned to create a new version:

version_2 = automation.clone()

assert version_2.version == 2
assert automation.version == 1

The automation definition is intentionally independent from triggers. A definition describes what runs, while triggers describe when it runs.

Automation Runs

AutomationRun represents one execution of an automation definition.

from bindai_automation import AutomationRun

run = AutomationRun(
    definition_id=automation.id,
    definition_version=automation.version,
    input={"message": "hello"},
)

run.start()

# Execute the automation target here.

run.complete(output={"result": "done"})

An automation run provides:

id — unique execution identifier
definition_id — automation definition identifier
definition_version — definition version used for the execution
status — execution state such as pending, running, completed, or failed
input — optional execution input
output — execution output
error — failure information when execution fails
created_at — run creation timestamp
started_at — execution start timestamp
completed_at — execution completion timestamp

Runs expose lifecycle methods:

run.start()

run.complete(output={"result": "done"})

run.fail("execution failed")

The run object represents execution state independently from the automation definition itself.

Automation State

AutomationStateStore defines the persistence contract for automation runs.

from bindai_automation import AutomationStateStore


class CustomAutomationStateStore(AutomationStateStore):
    def save(self, run): ...
    def load(self, run_id): ...
    def delete(self, run_id): ...

The state store is intentionally separate from AutomationRun. This allows execution state to be stored in memory or backed by another persistence system without coupling the run model to a specific storage implementation. The state store represents the current state of an automation run.

In-Memory State Store

MemoryAutomationStateStore provides an in-memory implementation of the automation state store.

from bindai_automation import MemoryAutomationStateStore

store = MemoryAutomationStateStore()

store.save(run)

loaded = store.load(run.id)

assert loaded is run

Runs can also be removed:

store.delete(run.id)

assert store.load(run.id) is None

The in-memory state store is intended as a lightweight implementation and as a foundation for future persistent storage backends.

Automation Run History

AutomationRunHistory defines the history contract for recording and retrieving automation runs.

from bindai_automation import AutomationRunHistory


class CustomAutomationRunHistory(AutomationRunHistory):
    def record(self, run): ...
    def get(self, run_id): ...
    def list(self): ...

Run history is intentionally separate from AutomationStateStore. The state store answers:

Where is the current execution state of this run?

Run history answers:

What automation runs have been recorded?

This separation allows current execution state and historical records to evolve independently. The history contract provides:

record(run) — record an automation run
get(run_id) — retrieve a historical run by ID
list() — retrieve recorded runs in insertion order

In-Memory Run History

MemoryAutomationRunHistory provides an in-memory implementation of AutomationRunHistory.

from bindai_automation import MemoryAutomationRunHistory

history = MemoryAutomationRunHistory()

run = AutomationRun(
    definition_id=automation.id,
    definition_version=automation.version,
)

run.start()

run.complete(output={"result": "done"})

history.record(run)

stored = history.get(run.id)

assert stored is not None
assert stored.id == run.id

Recorded runs are stored as snapshots. Later changes to the original AutomationRun do not modify the historical record:

run.output = {"result": "changed"}

stored = history.get(run.id)

assert stored is not None
assert stored.output == {"result": "done"}

The history implementation also returns independent snapshots when records are retrieved. The current implementation is intentionally lightweight and provides the foundation for future persistent run-history backends.

Background Automation Workers

AutomationWorker executes automation definitions and manages the lifecycle of their AutomationRun objects. It supports both synchronous execution and background submission:

from bindai_automation import AutomationWorker

worker = AutomationWorker()

run = worker.run(
    automation,
    input={"message": "hello"},
)

future = worker.submit(
    automation,
    input={"message": "hello"},
)

background_run = future.result()

worker.shutdown()

The worker:

creates an AutomationRun
persists the current run state through AutomationStateStore
executes the automation definition
updates the run lifecycle
records the completed or failed run through AutomationRunHistory

The worker uses a thread pool for background execution. The worker does not replace EventTrigger. Event triggers determine when an event should invoke application logic, while AutomationWorker provides background execution and run lifecycle management for automation definitions. The resulting architecture is:

Event Source
     |
     v
EventTrigger
     |
     v
Automation / Application Action
     |
     v
AutomationWorker
     |
     v
AutomationRun
     |
     +----------------------+
     |                      |
     v                      v
AutomationStateStore  AutomationRunHistory

Workers should be shut down when they are no longer required:

worker.shutdown()

They can also be used as context managers:

with AutomationWorker() as worker:
    run = worker.run(automation)

Trigger

Trigger is the base abstraction for automation triggers.

from bindai_automation import Trigger

A trigger has an enabled state and provides lifecycle operations:

trigger.enable()

trigger.disable()

trigger.attach()

trigger.detach()

The base interface defines:

enabled
enable()
disable()
attach()
detach()

Concrete trigger implementations determine how events are received and how automation actions are started.

Enabling and Disabling Triggers

Triggers can be temporarily disabled without removing them from their event source.

trigger.disable()

A disabled trigger remains attached but ignores incoming events. It can be enabled again:

trigger.enable()

This provides a simple mechanism for controlling automation without destroying the trigger configuration.

Event Triggers

EventTrigger connects a BindAI EventBus to a target callable.

from bindai_automation import EventTrigger

A trigger is created with:

an event bus
an event name
a target callable

For example:

trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=handle_event,
)

The target receives the published event:

def handle_event(event):
    print(event)

Attaching an Event Trigger

An EventTrigger must be attached to begin receiving events.

trigger.attach()

Once attached, matching events published through the configured EventBus are passed to the target.

EventBus
   |
   | matching event
   v
EventTrigger
   |
   v
target(event)

Calling attach() multiple times does not create duplicate subscriptions.

Detaching an Event Trigger

An attached trigger can be removed from its event source:

trigger.detach()

After detaching, the trigger no longer receives events from that subscription. Calling detach() when the trigger is already detached is safe. A typical lifecycle is:

trigger.attach()

# automation is active

trigger.detach()

Event Matching

EventTrigger subscribes to a specific event name. For example:

trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=handle_event,
)

Only events whose name matches the configured event name are delivered to the trigger by the underlying event bus subscription. The event itself is passed unchanged to the target callable.

Agent Events

BindAI agents expose an EventBus through:

agent.events

This makes the agent event system a natural source for automation triggers. For example:

from bindai_automation import EventTrigger


def handle_tool_event(event):
    print("Tool event received:", event)


trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=handle_tool_event,
)

trigger.attach()

The automation layer therefore builds on the existing BindAI event infrastructure rather than introducing a separate event mechanism.

Tool Execution Events

Agent tool execution publishes ToolExecutedEvent through the agent’s event bus. An automation trigger can subscribe to the corresponding event name. Conceptually:

Agent
  |
  +-- execute_tool()
          |
          v
    ToolExecutedEvent
          |
          v
       EventBus
          |
          v
     EventTrigger
          |
          v
        Target

This can be used to react to tool activity without modifying the tool execution pipeline.

Targets

An EventTrigger accepts a callable target:

def handle_event(event): ...

The target can contain application-specific automation logic. For example:

def notify(event):
    print("Automation triggered")

Then:

trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=notify,
)

The automation package does not impose a specific target type. The target can therefore be a function, callable object, or another compatible callable.

Trigger State

Triggers have two independent lifecycle concepts:

Attached
    |
    +---- Enabled
    |
    +---- Disabled

An attached trigger can be disabled:

trigger.attach()

trigger.disable()

Events can still reach the trigger’s subscription, but the trigger ignores them while disabled. It can later be re-enabled:

trigger.enable()

Alternatively, the subscription can be completely removed:

trigger.detach()

Trigger Registry

TriggerRegistry provides a registry for trigger instances.

from bindai_automation import TriggerRegistry

registry = TriggerRegistry()

A trigger can be registered under a key:

registry.register(
    "tool-events",
    trigger,
)

It can then be retrieved:

trigger = registry.get("tool-events")

A non-throwing lookup is also available:

trigger = registry.get_or_none("tool-events")

Registry Operations

TriggerRegistry provides operations for managing registered triggers.

registry.register("tool-events", trigger)

registry.get("tool-events")

registry.get_or_none("tool-events")

registry.contains("tool-events")

registry.remove("tool-events")

registry.clear()

The registry also exposes:

registry.keys()

registry.values()

registry.items()

and supports:

len(registry)

The registry is useful when an application needs to manage multiple automation triggers dynamically. Registering a trigger does not automatically attach it to its event source.

Example

A simple event-driven automation setup can look like this:

from bindai_automation import EventTrigger


def handle_event(event):
    print("Automation received:", event.name)


trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=handle_event,
)

trigger.attach()

The flow is:

Agent
  |
  v
EventBus
  |
  v
EventTrigger
  |
  v
handle_event()

When the automation is no longer required:

trigger.detach()

Multiple Triggers

An application can create multiple triggers for different events.

tool_trigger = EventTrigger(
    bus=agent.events,
    event_name="tool.executed",
    target=handle_tool_event,
)

agent_trigger = EventTrigger(
    bus=agent.events,
    event_name="agent.finished",
    target=handle_agent_event,
)

Each trigger can have its own lifecycle:

tool_trigger.attach()

agent_trigger.attach()

This keeps individual automation rules isolated.

Automation and Workflows

Automation triggers can be used as an integration boundary around workflows. Conceptually:

Event
  |
  v
EventTrigger
  |
  v
Workflow

The current automation package does not define a dedicated workflow-trigger execution API. Instead, the trigger target is a generic callable:

def start_automation(event): ...

Application code can use that callable to invoke whatever workflow or executable behavior is appropriate. Higher-level automation orchestration remains a separate layer of the framework.

Automation and Agents

Agents can act as event sources for automation. For example:

Agent
  |
  +-- EventBus
        |
        v
   EventTrigger
        |
        v
   Application Action

This allows applications to react to agent activity without coupling automation logic directly to the agent implementation.

Automation and Connections

Automation can also be combined with BindAI Connections. For example:

Agent Event
    |
    v
EventTrigger
    |
    v
Application Action
    |
    v
Connection
    |
    v
External Service

An application could use a trigger target to send information to an external service through a connection. The current automation package does not directly manage connections. That remains the responsibility of the application or integration layer.

Error Handling

The underlying BindAI EventBus isolates exceptions raised by individual event handlers. This means an exception raised while processing one event handler is logged by the event bus rather than preventing other subscribed handlers from being invoked. An EventTrigger itself does not introduce a separate retry or error-management system. Applications that require retries, persistence, or failure recovery should implement those concerns at the appropriate higher-level automation or workflow layer.

Synchronous Execution

The current EventBus implementation is synchronous. Therefore, an event handler is invoked as part of event publication. Conceptually:

publish(event)
      |
      v
EventTrigger
      |
      v
target(event)

The current EventTrigger does not create background workers or persistent automation jobs. For automation definitions that need background execution, BindAI provides AutomationWorker. The worker executes AutomationDefinition instances in a thread pool while managing AutomationRun, state-store, and run-history lifecycle. Therefore, event-driven triggering and background execution remain separate concerns.

Trigger Lifecycle

A recommended lifecycle is:

Create
  |
  v
Configure
  |
  v
Attach
  |
  v
Enabled
  |
  +---- Disable
  |       |
  |       v
  |     Disabled
  |       |
  |       v
  |     Enable
  |       |
  +-------+
  |
  v
Detach

For long-running applications, triggers should be detached when their subscription is no longer required.

Testing Automation

Automation components should be tested independently from the external services they eventually control. Useful tests include:

Trigger construction
Enable/disable behavior
Attach behavior
Detach behavior
Event matching
Target invocation
Duplicate attachment protection
Registry operations
Handler failure behavior
Automation run lifecycle
State-store operations
Run-history recording
Run-history retrieval
Run-history snapshot isolation
Background worker execution
Background worker state persistence
Background worker run-history recording
Worker shutdown behavior

Event buses can be used with test events and test callables so that automation behavior can be verified without external services.

Security Considerations

Automation can cause actions to occur automatically in response to events. Applications should therefore consider:

Which events can trigger automation
Which targets can be invoked
Whether the target performs external side effects
Credential and secret handling
Authorization boundaries
Input validation
Audit requirements

Automation targets should not expose secrets or credentials to event payloads unnecessarily. State-changing automation should receive appropriate validation and authorization controls.

Current Scope

The current BindAI Automation package provides:

Automation

AutomationDefinition
AutomationRun
AutomationStateStore
MemoryAutomationStateStore
AutomationRunHistory
MemoryAutomationRunHistory
AutomationWorker

Event integration

Trigger
EventTrigger
BindAI EventBus
Named event subscriptions
Event-driven callable targets
Enable/disable lifecycle
Attach/detach lifecycle

Registry support

TriggerRegistry
Trigger registration
Trigger lookup
Trigger removal
Trigger enumeration
Registry clearing

The package provides the foundation for stateful and event-driven automation without attempting to implement the entire automation platform in a single abstraction.

Future Automation Capabilities

The broader BindAI automation roadmap includes additional capabilities such as:

Advanced event routing
More trigger types
More advanced scheduling and execution policies
Persistent database-backed automation state
Persistent database-backed run history
Broader automation orchestration

These capabilities should build on the current automation definitions, execution state, run-history, trigger, event, and worker foundations.

Design Principles

BindAI Automation follows several principles:

Keep triggers small and composable.
Reuse the existing event system.
Separate event detection from automation actions.
Make trigger lifecycle explicit.
Avoid hidden background execution.
Keep external-service concerns outside the trigger abstraction.
Allow future trigger types without changing existing event infrastructure.
Keep automation state and persistence separate from basic event subscription.
Keep current execution state separate from historical run records.
Keep the initial history API small so persistent backends can be added later.
Keep background execution explicit through AutomationWorker.

API Accuracy

The current automation documentation intentionally describes only APIs implemented by the current bindai-automation package. The current automation package provides:

AutomationDefinition(...)

AutomationRun(...)

AutomationStateStore(...)

MemoryAutomationStateStore(...)

AutomationRunHistory(...)

MemoryAutomationRunHistory(...)

AutomationWorker(...)

Trigger(...)

EventTrigger(...)

TriggerRegistry(...)

The current automation layer does not claim to provide higher-level APIs such as:

automation.schedule(...)

automation.persist(...)

automation.worker(...)

trigger.retry(...)

trigger.schedule(...)

unless those capabilities are explicitly implemented elsewhere in BindAI. Automation run history is currently available through the AutomationRunHistory contract and its in-memory implementation, MemoryAutomationRunHistory. Persistent database-backed history remains future infrastructure. Background execution is currently available through AutomationWorker, which executes automation definitions using a thread pool and manages run state and history. Advanced event routing, persistent storage backends, and broader automation orchestration remain future infrastructure.

Summary

BindAI Automation provides a lightweight foundation for stateful and event-driven automation. The current architecture separates automation definitions, execution state, historical records, and event triggers:

AutomationDefinition
        |
        v
  AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore    AutomationRunHistory
        |                      |
        v                      v
Current Run State       Historical Runs

Event-driven automation is provided through:

Event Source
     |
     v
  EventBus
     |
     v
EventTrigger
     |
     v
  Target

Background automation execution is provided through:

AutomationDefinition
        |
        v
AutomationWorker
        |
        v
AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore    AutomationRunHistory

The main public abstractions are:

from bindai_automation import (
    AutomationDefinition,
    AutomationRun,
    AutomationRunHistory,
    AutomationStateStore,
    AutomationWorker,
    MemoryAutomationRunHistory,
    MemoryAutomationStateStore,
    Trigger,
    EventTrigger,
    TriggerRegistry,
)

Triggers can be attached, detached, enabled, and disabled. EventTrigger connects BindAI’s existing EventBus system to application-defined callable targets, while TriggerRegistry provides centralized trigger management. AutomationRun provides execution state, AutomationStateStore provides current-state persistence, and AutomationRunHistory provides a separate interface for historical execution records. AutomationWorker provides explicit background execution for automation definitions using a thread pool while coordinating run state and history. The current in-memory implementations provide the foundation for future persistent storage, advanced event routing, and broader automation orchestration.

​Automation

​Automation Architecture

​Automation Package

​Automation Definitions

​Automation Runs

​Automation State

​In-Memory State Store

​Automation Run History

​In-Memory Run History

​Background Automation Workers

​Trigger

​Enabling and Disabling Triggers

​Event Triggers

​Attaching an Event Trigger

​Detaching an Event Trigger

​Event Matching

​Agent Events

​Tool Execution Events

​Targets

​Trigger State

​Trigger Registry

​Registry Operations

​Example

​Multiple Triggers

​Automation and Workflows

​Automation and Agents

​Automation and Connections

​Error Handling

​Synchronous Execution

​Trigger Lifecycle

​Testing Automation

​Security Considerations

​Current Scope

​Automation

​Event integration

​Registry support

​Future Automation Capabilities

​Design Principles

​API Accuracy

​Summary

Automation

Automation Architecture

Automation Package

Automation Definitions

Automation Runs

Automation State

In-Memory State Store

Automation Run History

In-Memory Run History

Background Automation Workers

Trigger

Enabling and Disabling Triggers

Event Triggers

Attaching an Event Trigger

Detaching an Event Trigger

Event Matching

Agent Events

Tool Execution Events

Targets

Trigger State

Trigger Registry

Registry Operations

Example

Multiple Triggers

Automation and Workflows

Automation and Agents

Automation and Connections

Error Handling

Synchronous Execution

Trigger Lifecycle

Testing Automation

Security Considerations

Current Scope

Automation

Event integration

Registry support

Future Automation Capabilities

Design Principles

API Accuracy

Summary